<html>
<head>
<title>User Manual: Dotdir</title>
<link href="./page.css" rel="stylesheet" type="text/css"/>
<link href="./olive.css" rel="stylesheet" type="text/css"/>
<link href="./manual.css" rel="stylesheet" type="text/css"/>
</head>
<body>

<h1>5. The Dotdir</h1>
<p>
(Feeds) <a href="feeds.html">Prev</a>
| <a href="index.html">Index</a> | Next
</p>
<hr/>

<p><i>
  None of the information in this section of the manual is needed to
  use and enjoy Olive.
</i></p>

<p>
  Olive keeps its configuration, raw data, and working data in a
  directory named '<code>~/.olive</code>'. This section describes the
  contents of that directory.
</p>


<h2 id="s10">5.1 The Config File</h2>
<p>
  The configuration file is named '<code>olive.yaml</code>'. As its
  extension indicates, it is
  a <a href="http://yaml.org/">YAML</a>-formatted file. If you are
  unfamiliar with YAML, you should read about it before manually
  editing this file.
</p>
<h3 id="s11">5.1.1 Miscellaneous Configuration</h3>
<p>
</p>
<dl>
  <dt>coe</dt>
  <dd>
    <b>Mnemonic:</b> Confirm On Exit<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether Olive termination is immediate (0)
    or confirmed (1). See <a href="options.html#s25">Section 3.2.5</a>.
  </dd>
  <dt>dst</dt>
  <dd>
    <b>Mnemonic:</b> Don't Show Titlebar<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether the first line of the Olive window
    is used as a titlebar (0) or to display live list data
    (1). See <a href="options.html#s24">Section 3.2.4</a>.
  </dd>
  <dt>fr</dt>
  <dd>
    <b>Mnemonic:</b> First Run<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Originally marked whether Olive had been run before
    (1) or not (0). Now used to store the version number of Olive when
    last run, paving the way for automatic upgrade procedures. Still
    controls display of the first-run splash screen,
  </dd>
  <dt>gsp</dt>
  <dd>
    <b>Mnemonic:</b> Global Story Paging<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether keybindings are enabled so as to
    allow paging of the currently displayed story no matter where
    focus is. 1 is "bind", 0 is "don't
    bind". See <a href="options.html#s24">Section 3.2.4</a>.
  </dd>
  <dt>pw</dt>
  <dd>
    <b>Mnemonic:</b> Poll Wait<br/>
    <b>Type:</b> Positive Integer<br/>
    <b>Effect:</b> Sets the inital value, in minutes, of the delay
    between automatic poll feeds. See
    sections <a href="options.html#s30">3.3</a>
    and <a href="feeds.html#s40">4.4</a> for more info.
  </dd>
  <dt>sls</dt>
  <dd>
    <b>Mnemonic:</b> Show List Status<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls whether the status line will display story
    list stats (1) or not (0). See <a href="options.html#s21">Section
    3.2.1</a>.
  </dd>
  <dt>snu</dt>
  <dd>
    <b>Mnemonic:</b> Skip to Next Unread<br/>
    <b>Type:</b> Boolean<br/>
    <b>Effect:</b> Controls the behavior of the prev/next commands:
    always select the story adjacent to the current selection (0) or
    seek to the next unread story
    (1). See <a href="options.html#s22">Section 3.2.2</a>.
  </dd>
  <dt>to</dt>
  <dd>
    <b>Mnemonic:</b> Time-Out<br/>
    <b>Type:</b> Positive Integer<br/>
    <b>Effect:</b> Sets the initial value for the network timeout of
    the internal LWP::UserAgent object which fetches
    feeds. See <a href="options.html#s40">Section 3.4</a>.
</dd>
  <dt>www</dt>
  <dd>
    <b>Mnemonic:</b> ...<br/>
    <b>Type:</b> String<br/>
    <b>Effect:</b> Contains the command string which is used to launch
    external browser sessions. See <a href="options.html#s50">Section
    3.5</a>.
  </dd>
</dl>
<h3 id="s12">5.1.2 Feeds</h3>
<p>
  All information about subscribed feeds is stored in a HOHOH named
  '<code>feeds</code>'. The full format is as follows:
</p>
<pre><code>  feeds:
    a_feed:
      disp: Display Title From User
      dormant: 0
      feed: http://feed/url
      force: 0
      last: 1119248150
      title: Actual Title From RSS Feed
      ttl: 86400
</code></pre>
<p>
  Where the '<code>a_feed</code>' stanza is repeated, with appropriate
  changes, for each subscribed feed. The meanings of the individual
  values is:
</p>
<ol>
  <li><b>disp:</b> The feed's user-chosen display name; displayed in
  the List Pane next to stories belonging to this feed.</li>
  <li><b>dormant:</b> Boolean marking the feed dormant or not.</li>
  <li><b>feed:</b> URL of the actual feed.</li>
  <li><b>force:</b> Boolean marking the feed as force-fetchable or not.</li>
  <li><b>last:</b>Value of <code>time()</code> as of the feed's last fetching.</li>
  <li><b>title:</b> Actual title of the feed, taken from the feed data.</li>
  <li><b>ttl:</b> The feed's time-to-live in seconds. Taken from the
  feed or given a value of 3600s in the absence of a value from the
  feed data.</li>
</ol>
<p>
  See <a href="feeds.html">Section 4</a> for more information.
</p>
<h3 id="s13">5.1.3 Customizing Keybindings</h3>
<p>
  There is no interface provided for changing keybindings within
  Olive. Not all functions can be rebound. The ones which can are
  altered via a HOH named '<code>keys</code>' in the config file. An
  example which creates custom bindings for the functions normally
  assigned to the '<code>[</code>' and '<code>]</code>' keys is:
</p>
<pre><code>  keys:
    next: n
    prev: p
</code></pre>
<p>
  Here is the list of bindable functions and their standard keys:
</p>
<table>
  <tr><th>Function</th><th>Key</th><th>Description</th></tr>
  <tr>
    <td>prev</td>
    <td><code>[</code></td>
    <td>Go to previous story</td>
  </tr>
  <tr>
    <td>next</td>
    <td><code>]</code></td>
    <td>Go to next story</td>
  </tr>
  <tr>
    <td>mark</td>
    <td><code>m</code></td>
    <td>Mark story read</td>
  </tr>
  <tr>
    <td>unmark</td>
    <td><code>u</code></td>
    <td>Mark story unread (unmark story)</td>
  </tr>
  <tr>
    <td>star</td>
    <td><code>s</code></td>
    <td>Toggle story starred/unstarred</td>
  </tr>
  <tr>
    <td>markall</td>
    <td><code>M</code></td>
    <td>Mark all stories read</td>
  </tr>
  <tr>
    <td>unmarkall</td>
    <td><code>U</code></td>
    <td>Mark all stories unread (unmark all)</td>
  </tr>
  <tr>
    <td>gpdn</td>
    <td>'<code> </code>' (Space)</td>
    <td>Global story paging: pagedown</td>
  </tr>
  <tr>
    <td>gpup</td>
    <td><code>-</code></td>
    <td>Global story paging: pageup</td>
  </tr>
  <tr>
    <td>focus</td>
    <td><code>w</code></td>
    <td>Shift focus between list/story panes</td>
  </tr>
  <tr>
    <td>link</td>
    <td><code>l</code></td>
    <td>Execute defined link command with story URL</td>
  </tr>
  <tr>
    <td>poll</td>
    <td><code>p</code></td>
    <td>Poll for updated feeds</td>
  </tr>
  <tr>
    <td>force</td>
    <td><code>P</code></td>
    <td>Force-poll feeds marked as forced</td>
  </tr>
  <tr>
    <td>filterf</td>
    <td><code>F</code></td>
    <td>Filter story list to show only stories from flagged feeds</td>
  </tr>
  <tr>
    <td>filters</td>
    <td><code>S</code></td>
    <td>Filter story list to show only starred stories</td>
  </tr>
</table>

<p>
  Olive does not check for duplicate bindings or stomping on a
  prebound key without providing a replacement. Also, be aware that
  you may need to quote your choice of key if it is a YAML special
  character (see the YAML spec for more information).
</p>


<h2 id="s20">5.2 The Error Log</h2>
<p>
  Olive logs all warnings and fatal error messages (trapped or
  otherwise) to a file named '<code>errors.log</code>'. On startup,
  this file is copied to '<code>errors.log.1</code>' before being
  overwritten, so there are logs for the past 2 runs available at any
  time.
</p>
<p>
  Error logs always start with a timestamp like this:
</p>
<pre><code>  -- Starting up at 2005-05-22T16:58:11 --
</code></pre>
<p>
  After that, there is no standard or predictable format for the
  contents of the file.
</p>
<p>
  Should Olive ever suddenly quit, or if you experience any problems
  or weird behavior, please look at the logfile(s) and file a bug (as
  per <a href="start.html#s50">Section 1.5</a>)
</p>

<h2 id="s30">5.3 The Story Database</h2>
<p>
  Olive does not operate upon the raw feeds it fetches over the
  network. It processes them after they are retrieved and stores
  the relevant data in a <a href="http://sqlite.org/">SQLite</a>
  database named '<code>story.db</code>'.
</p>
<p>
  The schema of the database is as follows:
</p>
<pre><code>  CREATE TABLE stories (id INTEGER PRIMARY KEY, 
                        nick TEXT, 
                        timestamp INT,
                        md5 TEXT, 
                        read INT, 
                        new INT, 
                        link TEXT, 
                        title TEXT, 
                        desc TEXT);
</code></pre>



<h2 id="s40">5.4 The Feeds Directory</h2>
<p>
  Downloaded feeds and the data needed to perform tests for HTTP 304
  status are stored in a subdirectory called
  '<code>feeds</code>'. Every feed you're subscribed to will have two
  files there, a file named as a possibly modified form of the feed
  nickname, and file with the same name as the first one, but with
  ".cache" appended.
</p>
<pre class='screen'>  mdxi@fornax:~$ ls .olive/feeds/
  atc             cnn_money        groklaw        mdxi         rjbs        
  atc.cache       cnn_money.cache  groklaw.cache  mdxi.cache   rjbs.cache  
  bbc_news        gloria           kate           olive        robert      
  bbc_news.cache  gloria.cache     kate.cache     olive.cache  robert.cache
</pre>
<p>
  The files with no extension hold the last downloaded copy of that
  feed. The <code>.cache</code> files hold HTTP header data needed to
  check if the feed has been updated when it is polled next.
</p>
<p>
  Files associated with a feed are unlinked when the feed is removed
  from your feed list.
</p>

<hr/>
<p>
(Feeds) <a href="feeds.html">Prev</a>
| <a href="index.html">Index</a> | Next
</p>
<hr/>
<p>
$Id: dotdir.html 366 2006-01-03 02:35:27Z mdxi $
</p>
</body>
</html>
